---
title: "Switch"
description: "The Switch component is used as an alternative between checked and not checked states."
---

import {switchContent} from "@/content/components/switch";

# Switch

The Switch component is used as an alternative between checked and not checked states.

<ComponentLinks component="switch" styles="toggle" reactAriaHook="useSwitch" />

---

<CarbonAd/>

## Installation

<PackageManagers
  showGlobalInstallWarning
  commands={{
    cli: "npx heroui-cli@latest add switch",
    npm: "npm install @heroui/switch",
    yarn: "yarn add @heroui/switch",
    pnpm: "pnpm add @heroui/switch",
    bun: "bun add @heroui/switch"
  }}
/>


## Import

<ImportTabs
  commands={{
    main: 'import {Switch} from "@heroui/react";',
    individual: 'import {Switch} from "@heroui/switch";',
  }}
/>

## Usage

<CodeDemo title="Usage" files={switchContent.usage} />

### With Label

<CodeDemo title="With Label" files={switchContent.label} />

### Disabled

<CodeDemo title="Disabled" files={switchContent.disabled} />

### Sizes

<CodeDemo title="Sizes" files={switchContent.sizes} />

### Colors

<CodeDemo title="Colors" files={switchContent.colors} />

### With Thumb Icon

<CodeDemo title="With Thumb Icon" files={switchContent.thumbIcon} />

### With Icons

You can also add icons to start and end of the switch by using `startContent` and `endContent` props.

<CodeDemo title="With Icons" files={switchContent.icons} />

### Controlled

<CodeDemo title="Controlled" files={switchContent.controlled} />

> **Note**: HeroUI `Switch` also supports native events like `onChange`, useful for form libraries
> such as [Formik](https://formik.org/) and [React Hook Form](https://react-hook-form.com/).

## Slots

- **base**: Base slot for the switch. It is the main wrapper.
- **wrapper**: The wrapper of the start icon, end icon and thumb.
- **hiddenInput**: The hidden input element that is used to handle the switch state.
- **thumb**: The thumb element of the switch. It is the circle element.
- **label**: The label slot of the switch.
- **startContent**: The icon slot at the start of the switch.
- **endContent**: The icon slot at the end of the switch.
- **thumbIcon**: The icon slot inside the thumb.

### Custom Styles

You can customize the `Switch` component by passing custom Tailwind CSS classes to the component slots.

<CodeDemo title="Custom Styles" files={switchContent.customStyles} />

### Custom Implementation

In case you need to customize the switch even further, you can use the `useSwitch` hook to create your own implementation.

<CodeDemo title="Custom Implementation" files={switchContent.customImpl} />

<Spacer y={4} />

## Data Attributes

`Switch` has the following attributes on the `base` element:

- **data-selected**:
  When the switch is checked. Based on `isSelected` prop.
- **data-pressed**:
  When the switch is pressed. Based on [usePress](https://react-spectrum.adobe.com/react-aria/usePress.html)
- **data-readonly**:
  When the switch is readonly. Based on `isReadOnly` prop.
- **data-hover**:
  When the switch is being hovered. Based on [useHover](https://react-spectrum.adobe.com/react-aria/useHover.html)
- **data-focus**:
  When the switch is being focused. Based on [useFocusRing](https://react-spectrum.adobe.com/react-aria/useFocusRing.html).
- **data-focus-visible**:
  When the switch is being focused with the keyboard. Based on [useFocusRing](https://react-spectrum.adobe.com/react-aria/useFocusRing.html).
- **data-disabled**:
  When the switch is disabled. Based on `isDisabled` prop.

<Spacer y={4} />

## Accessibility

- Built with a native HTML `<input>` element.
- Full support for browser features like form autofill.
- Keyboard focus management and cross browser normalization.
- Keyboard event support for <Kbd>Tab</Kbd> and <Kbd>Space</Kbd> keys.
- Labeling support for assistive technology.
- Exposed as a switch to assistive technology via ARIA

<Spacer y={4} />

## API

### Switch Props

<APITable
  data={[
    {
      attribute: "children",
      type: "ReactNode",
      description: "The label of the switch.",
      default: "-"
    },
    {
      attribute: "value",
      type: "string",
      description: "The value of the input element, used when submitting an HTML form.",
      default: "-"
    },
    {
      attribute: "name",
      type: "string", 
      description: "The name of the input element, used when submitting an HTML form.",
      default: "-"
    },
    {
      attribute: "size",
      type: "sm | md | lg",
      description: "The size of the switch.",
      default: "md"
    },
    {
      attribute: "color",
      type: "default | primary | secondary | success | warning | danger",
      description: "The color of the switch.",
      default: "primary"
    },
    {
      attribute: "thumbIcon",
      type: "ThumbIconProps",
      description: "The icon to be displayed when the switch is checked.",
      default: "-"
    },
    {
      attribute: "startContent",
      type: "ReactNode",
      description: "The icon to be displayed at the start of the switch.",
      default: "-"
    },
    {
      attribute: "endContent", 
      type: "ReactNode",
      description: "The icon to be displayed at the end of the switch.",
      default: "-"
    },
    {
      attribute: "isSelected",
      type: "boolean",
      description: "Whether the element should be selected (controlled).",
      default: "-"
    },
    {
      attribute: "defaultSelected",
      type: "boolean",
      description: "Whether the element should be selected (uncontrolled).",
      default: "-"
    },
    {
      attribute: "isReadOnly",
      type: "boolean",
      description: "Whether the input can be selected but not changed by the user.",
      default: "-"
    },
    {
      attribute: "isDisabled",
      type: "boolean",
      description: "Whether the switch is disabled.",
      default: "false"
    },
    {
      attribute: "disableAnimation",
      type: "boolean",
      description: "Whether the animation should be disabled.",
      default: "false"
    },
    {
      attribute: "classNames",
      type: "Partial<Record<\"base\"｜ \"wrapper\"｜ \"thumb\"｜ \"label\" ｜ \"startContent\" ｜ \"endContent\" ｜ \"thumbIcon\" , string>>",
      description: "Allows to set custom class names for the switch slots.",
      default: "-"
    }
  ]}
/>

### Switch Events

<APITable
  data={[
    {
      attribute: "onChange",
      type: "React.ChangeEvent<HTMLInputElement>",
      description: "Handler that is called when the element's selection state changes. You can pull out the new checked state by accessing event.target.checked (boolean).",
      default: "-"
    },
    {
      attribute: "onValueChange",
      type: "(isSelected: boolean) => void",
      description: "Handler that is called when the element's selection state changes.",
      default: "-"
    }
  ]}
/>

### Types

#### Switch Icon Props

```ts
type IconProps = {
  "data-checked": string;
  width: string;
  height: string;
  isSelected: boolean;
  className: string;
};

type CheckboxIconProps = ReactNode | ((props: IconProps) => ReactNode);
```
